.\" groff -man -Tascii aclip.1
.TH arcan 1 "January 2018" arcan-wayland "User manual"
.SH NAME
arcan-wayland \- protocol bridge for Wayland support in Arcan
.SH SYNOPSIS
.B arcan-wayland [OPTIONS]

.SH DESCRIPTION
This tool act as a protocol service that implements the Wayland protocol.
It can be used to run Wayland conforming clients, and X clients if Xwayland
if installed. You can run it as a persistent service managing multiple
clients, or as a 'per application' chain loader.

.SH OPTIONS
.IP "\fB\-exec \fIbinary [args]\fR"
This argument sets the bridge to work in single client mode, and it is the
execution mode with the strongest separation between clients. All argument
processing after exec will be forwarded to the specified binary.

.IP "\fB\-xwl"
This enabled X- wayland mode, which spawns an X server (Xwayland) along with
a window manager (arcan_xwm) that implements X specific behavior. As some
applications radically change their behavior depending on if an X server is
available or not, the safest and best option is to pair this with -exec.

.IP "\fB\-dir \fI/prefix/path\fR"
Setting this argument changes the scratch directory that is used to set up
the compartments for each individual client (XDG_RUNTIME_DIR). This defaults
to the /tmp directory. It is very important that the backing store for this
path is a temporary (memory mapped) filesystem, as the client may use it to
allocate and transfer graphics buffers.

.IP "\fB\-sandbox\fR"
Enable syscall filtering and possibly other sandboxing mechanisms. This is
not enabled by default as there is a possibility that changes to the wayland
implementation libraries might require features that are blocked, and the
user should be actively aware of that..

.IP "\fB\-defer-release\fR"
This argument is used as an option for certain clients that produce frames
very aggressively. Many clients are written with double buffering in mind,
one frame committed and locked while another is being processed. Since
arcan-wayland essentially double-buffers internally, client submitted
buffers will be released almost immediately. This breaks some clients,
making them consume high CPU rates or even crash. With this argument, the
release of one buffer will only be performed when another is submitted to
replace it.

.IP "\fB\-shm-egl\fR"
Normally, shared memory source buffers gets copied and forwarded to the
main arcan instance as is. This costs an extra copy, but allows the bridge
to run without GPU access. By setting this flag, the cost of uploading a
shared memory buffer to the GPU will be absorbed by the bridge, forwarding
an accelerated handle onwards.

.IP "\fB\-width px -height px\fR"
Normally, the default output provided to wayland clients will get its values
from the initial values presented by the display/outputhints from the server
side. These two arguments can be used to force-override those values. This
might help work around problems with legacy wl_shell applications that respond
poorly to configure events.

.IP "\fB\-force-fs\fR"
This extends the -width and -height arguments with the option to make sure
that all configure events from the server are reset to the set initial width/
height, essentially disabling resize behavior.

.SH PROTOCOL CONTROL
Wayland is not a single protocol as much as it is a suite of possible protocols.
Each client may have different sets of required protocols and may refuse to work
or even change behavior based on which ones that are available.

To assist working around such issues, most sub- protocols can be disabled on
launch. Combined with the -exec option, this allows fine-grained segmentation
of which clients have access to what features.

To achieve that, look in the 'Protocol Filter' output when running arcan-wayland
with the --help option and follow the pattern of --no-XXX where XXXX is
substituted with the protocol in question.

.SH DEBUGGING / TROUBLESHOOTING
Wayland client support and conformance vary wildly, as does the conformance of
the bridge interpretation in itself, as the options for testing and verifying
protocol behaviors are very limited and the documentation fragmented and
incomplete. To assist with debugging wayland client behaviors, we have a number
of tools.

One option is setting the WAYLAND_DEBUG=1 environment variable which enables
debug output from the low level protocol behavior. Another is using
ARCAN_SHMIF_DEBUG=1 to enable debug output from the corresponding arcan event
queues.

If you invoke the arcan-wayland bridge with -trace, you can tune which
subprotocol implementations that gets debug output added. Running the bridge
without any arguments will show a list of the available values, these act as
a bitmask so you bitwise OR the values together in order to support multiple
trace outputs.

If the bridge is started with the -debugusr1 argument, you can send the USR1
signal to the process in order to get a snapshot of the allocation mask. This
is often useful as the allocation and deallocation rules and behaviors in
Wayland are much too complicated.

When running X clients via the waybridge you have additional environment
variables to log the state output of the window manager process. These are
ARCAN_XWLWM_LOGOUT that sets its output to stderr, which should be the same
stderr as that of waybridge process. The other is ARCAN_XWLWM_DEBUGSTALL which
enters a while(volatile_var){} loop before setting up Xwayland and connecting
the WM. This allows you to attach a debugger and release the variable manually
instead of relying on debugging the bridge and having the debugger survive the
fork and exec steps.

If you have access to the arcan source repository, there is also a tool that
can be built (shmmon) which allows inspection of data on the various surfaces.

.SH EXAMPLES

.PP
This example launches a single gtk3-demo session.

.B arcan-wayland -sandbox -shm-egl -exec gtk3-demo

This example requires both Xwayland arcan_xwm binaries to be present
and reachable in PATH.

.B arcan-wayland -xwl -exec xterm

.SH COPYRIGHT
Copyright  ©  2018-2019 Bjorn Stahl. 3-clause BSD licensed. This is free
software: you are free  to  change and redistribute it. There is NO WARRANTY,
to the extent permitted by law.

.SH AUTHOR
Bjorn Stahl <contact at arcan-fe dot com>
